Skip to content

DOC: Document behaviour of head(n), tail(n) for negative values of n except on GroupBy #30556

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Dec 30, 2019

Conversation

bharatr21
Copy link
Contributor

@bharatr21 bharatr21 commented Dec 30, 2019

Output of python3 scripts/validate_docstrings.py pandas.DataFrame.head

################################################################################
###################### Docstring (pandas.DataFrame.head)  ######################
################################################################################

Return the first `n` rows.

This function returns the first `n` rows for the object based
on position. It is useful for quickly testing if your object
has the right type of data in it.

For negative values of `n`, this function returns all rows except
the last `n` rows, equivalent to ``df[:-n]``.

Parameters
----------
n : int, default 5
    Number of rows to select.

Returns
-------
same type as caller
    The first `n` rows of the caller object.

See Also
--------
DataFrame.tail: Returns the last `n` rows.

Examples
--------
>>> df = pd.DataFrame({'animal': ['alligator', 'bee', 'falcon', 'lion',
...                    'monkey', 'parrot', 'shark', 'whale', 'zebra']})
>>> df
      animal
0  alligator
1        bee
2     falcon
3       lion
4     monkey
5     parrot
6      shark
7      whale
8      zebra

Viewing the first 5 lines

>>> df.head()
      animal
0  alligator
1        bee
2     falcon
3       lion
4     monkey

Viewing the first `n` lines (three in this case)

>>> df.head(3)
      animal
0  alligator
1        bee
2     falcon

For negative values of `n`

>>> df.head(-3)
      animal
0  alligator
1        bee
2     falcon
3       lion
4     monkey
5     parrot

################################################################################
################################## Validation ##################################
################################################################################

Docstring for "pandas.DataFrame.head" correct. :)

Output of python3 scripts/validate_docstrings.py pandas.DataFrame.tail

################################################################################
###################### Docstring (pandas.DataFrame.tail)  ######################
################################################################################

Return the last `n` rows.

This function returns last `n` rows from the object based on
position. It is useful for quickly verifying data, for example,
after sorting or appending rows.

For negative values of `n`, this function returns all rows except
the first `n` rows, equivalent to ``df[n:]``.

Parameters
----------
n : int, default 5
    Number of rows to select.

Returns
-------
type of caller
    The last `n` rows of the caller object.

See Also
--------
DataFrame.head : The first `n` rows of the caller object.

Examples
--------
>>> df = pd.DataFrame({'animal': ['alligator', 'bee', 'falcon', 'lion',
...                    'monkey', 'parrot', 'shark', 'whale', 'zebra']})
>>> df
      animal
0  alligator
1        bee
2     falcon
3       lion
4     monkey
5     parrot
6      shark
7      whale
8      zebra

Viewing the last 5 lines

>>> df.tail()
   animal
4  monkey
5  parrot
6   shark
7   whale
8   zebra

Viewing the last `n` lines (three in this case)

>>> df.tail(3)
  animal
6  shark
7  whale
8  zebra

For negative values of `n`

>>> df.tail(-3)
   animal
3    lion
4  monkey
5  parrot
6   shark
7   whale
8   zebra

################################################################################
################################## Validation ##################################
################################################################################

Docstring for "pandas.DataFrame.tail" correct. :)

Output of ./ci/code_checks.sh doctests passed for groupby.py

Copy link
Contributor

@TomAugspurger TomAugspurger left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This looks nice. I think we'll leave #30192 open to either implement this for GroupBy or raise.

@TomAugspurger
Copy link
Contributor

@Bharat123rox can you verify that we have unit tests for negative values in DataFrame.head?

@bharatr21
Copy link
Contributor Author

bharatr21 commented Dec 30, 2019

We do have the unit tests 👍, so this is the expected behaviour I guess...

# neg index
self._compare(o.head(-3), o.head(7))
self._compare(o.tail(-3), o.tail(7))

@TomAugspurger
Copy link
Contributor

Thanks!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants